fix(service-analytics): a draft-preview dataset response describes its columns like the live one (#16097) - #16192

Fixes #16097

A dataset queried while its base object had a pending seed draft came back with no column metadata at all. AnalyticsService.queryDataset's ADR-0037 P3 draft-preview branch returns immediately, and the ADR-0021 result-column enrichment runs ~250 lines later, so a preview response never reached it.

Both sites, re-located on current head

The card quoted 1115 / 1367 and triage quoted 1107 / 1401; #16101 landed in this same file in between and moved both. Measured on main @ 7d7ca6c0c, the branch point of this PR:

Driven, not read

One dataset, one row set, two AnalyticsService instances differing in exactly one config key (draftRowsResolver), so the only thing that can differ between the two responses is the enrichment. Before:

live    {"name":"category","type":"string","label":"Category"}
preview {"name":"category","type":"string"}
live    {"name":"expense_count","type":"number","builtinAggregate":"count"}
preview {"name":"expense_count","type":"number"}
live    {"name":"total_amount","type":"number","label":"Total Amount","format":"$0,0","currency":"EUR"}
preview {"name":"total_amount","type":"number"}
live    {"name":"avg_margin","type":"number","label":"Avg Margin","format":"0.0%","percentScale":"whole"}
preview {"name":"avg_margin","type":"number"}
live    {"name":"latest_spend","type":"time","label":"Latest Spend"}
preview {"name":"latest_spend","type":"number"}

After: every one of those preview rows equals its live row. The regression test asserts it per key and as a block, and the fixture lives in preview-column-enrichment.test.ts.

Per-key decision — each key checked, not copied wholesale

Every key the block writes is read off the dataset (the authored measure or dimension) and sourceFieldMeta (the source object's declared field metadata). None is read off rows. That is the whole reason one seam can serve both paths, and it is checked per key rather than assumed:

Ordering, per triage's second note: #16101 landed first, so this PR carries the correction TO preview rather than the other way round. The acceptance table is six rows, not five.

What is left skipped, and why that is a different question

Dimension VALUE label resolution stays skipped on the preview path. The standing comment's reasoning holds and is untouched in substance: drafted seed rows reference lookups by NAME (the seed convention), so there is no id to resolve and the value already reads well. What changed is that the comment now says which question it answers — it is a statement about ROW VALUES, and it never covered COLUMN descriptors, which come from the authored measure and which no property of the seed rows can supply.

That fence is pinned, not just asserted in prose: the test drives a lookup dimension both ways, shows the live path rewriting the row value to the resolved name, shows the preview path leaving the seed's own name, and asserts fetchRecordLabels was not called at all on the preview path.

Scope call worth a reviewer's eye

The card and triage enumerate the five measure keys. The measured before/after shows the dimension column header (category losing Category) going missing on the same path, from the same cause — a second result.fields descriptor pass, ~40 lines after the measure one, reading dimension.label off the authored dataset. It is included here because it is the same defect class in the same seam, and because shipping measure headers while leaving dimension headers bare would be a new inconsistency nobody asked for. It is emphatically not the fenced skip: that one rewrites row values, this one only describes columns. Happy to split it out if the lane wants the narrower diff.

Shape

Rather than copy the block onto a second path, it is extracted into one enrichResultColumns seam both paths call — the same argument #16101's type correction already makes for living in this method at all: one rule, not two implementations free to drift. A small selectedDimensions helper is extracted alongside it so drill metadata, row-value label resolution and the column headers keep answering "which dimensions" the same way.

Known-divergent, deliberately not pinned, handed to the PM to file

Two preview/live differences survive this change. Both are produced before any enrichment, by evaluateAnalyticsQueryOverRows in preview-evaluator.ts, so no descriptor pass can reach them:

1. aggregate() coerces with Number() and drops non-finite values, so min/max over a non-numeric field returns 0 on the preview path. Measured: latest_spend is "2026-05-12" on live and 0 on preview.
2. The fields mint types every dimension column 'string', so a time dimension is 'string' on preview and 'time' on live.

Finding 1 meets this PR at exactly one point: latest_spend is now correctly described as type: 'time' on both paths, which is what its authored max over a date field means, while the preview VALUE beside it stays wrong until the evaluator is fixed. The descriptor is not withheld to accommodate a producer defect — that would be a consumer-side fallback in descriptor form (Prime Directive #12), and it would make the response's account of a column depend on a bug. Before this change the preview was wrong twice (no descriptor AND a zeroed value); now it is wrong once, visibly.

Neither is asserted in the new test, so fixing them will not have to red this file.

⚠️ Neither could be filed from this seat. Repo-scoped REST reads answer 403 for this session (GitHub access is not enabled for this session) and gh is absent, so the fallback is one targeted MCP search_issues for de-duplication — which answered API rate limit already exceeded. Filing without that de-duplication read is the one thing worse than not filing, so both findings are handed to the PM in the structured report with this reason attached, for filing against preview-evaluator.ts. They are recorded here so they cannot be lost with this session.

Verification

All exit codes captured immediately after a single redirected command, never through a pipe.

The gate family was derived mechanically, never hand-built, and re-derived on the final head. Two of the 56 first answered 3 = PREREQUISITE NOT MET and were converted into real measurements rather than reported as passes: check:dual-build-cjs-loads needed the full workspace build, and check:type-check-debt OOMed under --max-old-space-size=4096 (the gate names the caller's NODE_OPTIONS as the constraint) and was re-run at 8192, where its re-measure leg reports 140 raw tsc error(s) total, none above its recorded number.

Reverse verification, direction predicted before running. Deleting the enrichResultColumns(previewResult, …) call from the preview branch must red every preview assertion and leave the dimension-value-label fence case green — ordinary direction, no inversion, since the change only ADDS descriptor keys. Committed first, then mutated; mutation proven on disk by a git hash-object delta (e7a40f97… to 667e7c59…) plus anchored counts (1 to 0, with the live-path call still present at 1); restored under trap … EXIT INT TERM on an absolute path; restore proven by blob equality to HEAD: and an empty git diff HEAD. Measured 11 red / 1 green, and the 1 green is exactly the fence case.

Changeset

patch on @objectstack/service-analytics. It changes what a published wire surface produces on one path — POST /analytics/dataset/query with preview=draft now returns column descriptors it previously omitted. Additive on the response: no key changes meaning, none is removed, and the live path is byte-identical.

Not addressed here

• out of scope: A min/max over a text / select / lookup field is still described as type: "number" in the analytics response #16098 — min/max over text/select/lookup still typed number. Different population, its own card; measure-result-type.ts is untouched by this PR.
• out of scope: $icontains still compiles translate() on the unknown dialect arm, so a SQLite datasource whose dialect is unanswered still fails to parse — PR #16020's measured residue #16028 — text-match-sql.ts is untouched.

Every reading above — the union of gates, lint, the package suite, the consumers and the full build — was taken on final head 4636bcb2b, which is what this branch points at. No prediction is made here about CI state.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Generated by Claude Code